%==========================================================================
%=  This file is part of the Sound Restoration Project
%=  (c) Copyright Industrial Mathematics Institute
%=                University of South Carolina, Department of Mathematics
%=  ALL RIGHTS RESERVED
%=
%=  Author: Borislav Karaivanov
%==========================================================================

%==========================================================================
% List of the files on which this procedure depends:
%
% none
%
%==========================================================================

%==========================================================================
% The function "generateOutputDirectory" creates a name (including a full
% directory path) for a new output directory that resides inside a given
% parent directory, starts with a specified expression which includes a
% certain index fields, and has the smallest index that is greater than the
% indices of all existing directories whose names start with the same
% specified expression.
% INPUT: "parentDir" is a string specifying the name (including a full
% directory path) of the parent directory inside of which the new
% subdirectory is to reside.
% "descriptStr" is a string to be added at the end of the new directory
% name. It is intended to carry specific information about the intended
% content of the directory.
% "dirNamePrefixNoPath" is an optional string specifying a prefix for the
% output directory name (not including any directory path).
% "dirIndexLength" is an optional integer specifying the number of digits
% used to specify the index of an output directory in its file name.
% Indices are specified with leading zeros. For example, if the index field
% length is 3, then index of 5 is specified as 005 in the directory name.
% OUTPUT: "outDirPath" returns the name of the new output directory
% (including a full directory path).
%==========================================================================
function outDirPath = generateOutputDirectory(parentDir, descriptStr, ...
    dirNamePrefixNoPath, dirIndexLength)

if (nargin < 3)
    dirNamePrefixNoPath = 'Run';
end
if (nargin < 4)
    dirIndexLength = 3;
end

% Make sure that the string specifying the parent directory end with a
% file separator.
if (strcmpi(parentDir(end), filesep) == false)
    parentDir = [parentDir filesep];
end

% Get a list of all files and subdirectories in the given directory.
fileAndDirListArr = dir(parentDir);
% Extract the subdirectories only.
dirListArr = fileAndDirListArr([fileAndDirListArr.isdir]);
% Extract the names of the subdirectories.
dirNamesCellArr = {dirListArr.name};

% Find the directories which start with a specified expression.
matchExpr = ['^' dirNamePrefixNoPath '\d{' num2str(dirIndexLength) '}'];
funHandle = @(parseExpr) isempty(regexp(parseExpr, matchExpr, 'match', 'once'));
dirNamesCellArr = dirNamesCellArr(~cellfun(funHandle, dirNamesCellArr));

% Find the largest index among those of the found directories starting with
% the specified expression.
funHandle = @(str) str((numel(dirNamePrefixNoPath) + 1):(numel(dirNamePrefixNoPath) + dirIndexLength));
indexStrCellArr = cellfun(funHandle, dirNamesCellArr, 'UniformOutput', false);
maxInd = max(str2double(indexStrCellArr));
if isempty(maxInd)
    maxInd = 0;
end

% Construct a new directory name with the smallest index that is greater
% than the indices of all existing directories.
outDirPath = [parentDir dirNamePrefixNoPath num2str(maxInd + 1, ['%0' num2str(dirIndexLength) 'd'])];
% If the description string is non-empty, then append it to the directory
% name but first prefix it with an underscore.
if (~isempty(descriptStr))
    outDirPath = [outDirPath '_' descriptStr];
end
outDirPath = [outDirPath filesep];

return;
% end of the function "generateOutputDirectory"
